OPENDIR

Section: MINTLIB LIBRARY FUNCTIONS (3)
Updated: 3 March 1993
Index Return to Main Contents

NAME

directory, opendir, readdir, telldir, seekdir, rewinddir, closedir - directory operations

SYNOPSIS

#include <dirent.h>

DIR *opendir(const char *dirname);

struct dirent *readdir(DIR *dirp);

off_t telldir(DIR *dirp);

void seekdir(DIR *dirp, off_t loc);

void rewinddir(DIR *dirp);

int closedir(DIR *dirp);

DESCRIPTION

opendir opens the directory named by dirname and associates a directory stream with it. opendir returns a pointer to be used to identify the directory stream in subsequent operations. A NULL pointer is returned if dirname cannot be accessed or is not a directory, or if it cannot malloc enough memory to hold the whole thing. readdir returns a pointer to the next directory entry. It returns NULL upon reaching the end of the directory or detecting and invalid seekdir operation. telldir returns the current location associated with the named directory stream. seekdir sets the position of the next readdir operation on the directory stream. The new position reverts to the one associated with the directory stream when the telldir operation was performed. Values returned by telldir are good only for the lifetime of the DIR pointer from which they are derived. If the directory is closed and then reopened, the telldir value may be invalidated due to changes in the directory. rewinddir resets the position of the named directory stream to the beginning of the directory. It also causes the directory stream to refer to the current state of the corresponding directory, as a call to opendir would have done. closedir closes the named directory stream and frees the structure associated with the DIR pointer.

RETURN VALUES

opendir returns a pointer of type DIR on success. On failure, it returns NULL and sets errno to indicate the error. readdir returns a pointer of object type struct dirent on success. On failure, it returns NULL and sets errno to indicate the error. When the end of the directory is encountered, readdir returns NULL and leaves errno unchanged. The dirent structure is defined in <dirent.h> and contains the following fields of interest:

  struct dirent
  {
    long    d_ino;      /* garbage under TOS emulation  */
    off_t   d_off;      /* position in directory        */
    short   d_reclen;   /* length of d_name             */
    ...                 /* various TOS-emulation fields */
    char    *d_name;    /* name of the current file     */
  }; closedir returns 0 on succes, EIHNDL on failure. telldir returns the current location associated with the specified directory stream.

EXAMPLE

Sample code which searches a directory for entry `name' is:

    dirp = opendir(".");
    for (dp = readdir(dirp); dp != NULL; dp = readdir(dirp))
      if (!strcmp(dp->d_name, name))
      {
        closedir(dirp);
        return (FOUND);
      }
    closedir(dirp);
    return (NOT_FOUND);

NOTES

As memory is allocated at every call to opendir, every call to opendir should be matched by a corresponding call to closedir. When MiNT is not active, readdir calls are emulated under TOS. When that happens, various fields in the dirent structure are used that are undefined when MiNT is active. It is therefore advisable not to use those fields. Because of an error in the mintlibs and a change in MiNT 0.97, programs using readdir from the mintlibs pl 24 or below will die in MiNT 0.97 or higher.

This document was created by man2html, using the manual pages.
Time: 11:14:57 GMT, June 22, 2025